Configuring SIP Message Manipulation
The Message Manipulations table lets you configure up to
Each Message Manipulation rule is configured with a Manipulation Set ID. You can create groups (sets) of Message Manipulation rules by assigning each of the relevant Message Manipulation rules to the same Manipulation Set ID. The Manipulation Set ID is then used to assign the rules to specific calls:
■ |
|
● | Pre-classification Process: Message manipulation can be done on incoming SIP dialog-initiating messages (e.g., INVITE) prior to the classification process. You configure this by assigning the Manipulation Set ID to the SIP Interface on which the call is received (see Configuring SIP Interfaces). |
● | Post-classification Process: Message manipulation can be done on inbound and/or outbound SIP messages after the call has been successfully classified. Manipulation occurs only after the routing process - inbound message manipulation is done first, then outbound number manipulation (see Configuring IP-to-IP Outbound Manipulations), and then outbound message manipulation. For viewing the call processing flow, see Call Processing of SIP Dialog Requests. You configure this by assigning the Manipulation Set ID to the relevant IP Group in the IP Groups table (see Configuring IP Groups). |
■ | Gateway application: Message Manipulation rules are applied to calls as follows: |
● | Manipulating Inbound SIP INVITE Messages: Message manipulation can be applied only to all inbound calls (not specific calls). This is done by assigning a Manipulation Set ID, using the "global" parameter [GWInboundManipulationSet]. |
● | Manipulating Outbound SIP INVITE Messages: Message manipulation can be done for specific calls, by assigning a Manipulation Set ID to an IP Group in the IP Groups table, using the 'Outbound Message Manipulation Set' parameter. Message manipulation can be applied to all outbound calls (except for IP Groups that have been assigned a Manipulation Set ID). This is done by assigning a Manipulation Set ID, using the "global" parameter [GWOutboundManipulationSet]. |
■ | SIP requests initiated by the device |
The device also supports a built-in SIP message normalization feature that can be enabled per Message Manipulation rule. The normalization feature removes unknown SIP message elements before forwarding the message. These elements can include SIP headers, SIP header parameters, and SDP body fields.
The SIP message manipulation feature supports the following:
■ | Manipulation on SIP message type (Method, Request/Response, and Response type) |
■ | Addition of new SIP headers |
■ | Removal of SIP headers ("black list") |
■ | Modification of SIP header components such as values, header values (e.g., URI value of the P-Asserted-Identity header can be copied to the From header), call's parameter values |
■ | Deletion of SIP body (e.g., if a message body is not supported at the destination network this body is removed) |
■ | Translating one SIP response code to another |
■ | Topology hiding (generally present in SIP headers such as Via, Record Route, Route and Service-Route). |
■ | Configurable identity hiding (information related to identity of subscribers, for example, P-Asserted-Identity, Referred-By, Identity and Identity-Info) |
■ | Multiple manipulation rules on the same SIP message |
■ | Apply conditions per rule - the condition can be on parts of the message or call’s parameters |
■ | Apply Message Manipulation Set twice on SIP REGISTER messages -- first on the initial incoming unauthenticated REGISTER, and then again on the incoming authenticated SIP message received after the device sends a SIP 401 response for challenging the initial REGISTER request. For more information and for enabling this feature, see the [AuthenticatedMessageHandling] parameter. |
■ | Multiple manipulation rules using the same condition. The following figure shows a configuration example where Rules #1 and #2 ('Row Rule' configured to Use Previous Condition) use the same condition as configured for Rule #0 ('Row Rule' configured to Use Current Condition). For more information, see the description of the 'Row Rule' parameter in this section. |
The following figure illustrates an example of a SIP message that is manipulated by the device as follows:
1. | Removes the "Unknown_header: unknown_value" in the incoming message. |
2. | Changes the P-Asserted-Identity header value to "sip:200@10.33.216.1" in the outgoing message. |
This manipulation example is done by configuring two Message Manipulation rules, where Rule #1 is assigned to the source IP Group and Rule #2 to the destination IP Group.
Parameter |
Rule 1 |
Rule 2 |
---|---|---|
Message Type |
Invite.request |
Invite.request |
Condition |
Header.Unkown_header !contains 'unknown_value' |
Header.P-Asserted-Identity.URL.User == 'Susan' |
Action Subject |
Header.Unkown_header |
Header.P-Asserted-Identity |
Action Type |
Remove |
Modify |
Action Value |
|
'<sip:200@212.3.216.1>' |
● | For a detailed description of the syntax used for configuring Message Manipulation rules, refer to the document SIP Message Manipulation Reference Guide |
● | If you have configured call routing from the device's SBC application (IP-to-IP routing) to the device's Gateway application for IP-to-Tel routing, the device uses the initial SIP message as if it's a new call. Therefore, if any manipulations were done on the SIP message by the SBC application, the device ignores them. |
● |
|
● | Each message can be manipulated twice - on the source leg and on the destination leg (i.e., source and destination IP Groups). |
● | Unknown SIP parts can only be added or removed. |
● | SIP manipulations do not allow you to remove or add mandatory SIP headers. They can only be modified and only on requests that initiate new dialogs. Mandatory SIP headers include To, From, Via, CSeq, Call-Id, and Max-Forwards. |
● | The IP Group's 'SIP Group Name' parameter overrides inbound message manipulation rules that manipulate the host name in Request-URI, To, and/or From SIP headers. If you configure a SIP Group Name for the IP Group (see Configuring IP Groups) and you want to manipulate the host name in these SIP headers, you must apply your manipulation rule (Manipulation Set ID) to the IP Group as an Outbound Message Manipulation Set ('Outbound Message Manipulation Set' parameter), when the IP Group is the destination of the call. If you apply the Manipulation Set as an Inbound Message Manipulation Set ('Inbound Message Manipulation Set' parameter), when the IP Group is the source of the call, the manipulation rule will be overridden by the SIP Group Name. |
● | When configuring a Message Manipulation rule for manipulating a SIP header, the maximum length (characters) of the header's value in the incoming SIP message that can be manipulated is 4,096. |
The following procedure describes how to configure Message Manipulation rules through the Web interface. You can also configure it through ini file [MessageManipulations] or CLI (configure voip > message message-manipulations).
➢ | To configure SIP message manipulation rules: |
1. | Open the Message Manipulations table (Setup menu > Signaling & Media tab > Message Manipulation folder > Message Manipulations). |
2. | Click New; the following dialog box appears: |
3. | Configure a Message Manipulation rule according to the parameters described in the table below. |
4. | Click Apply. |
An example of configured message manipulation rules are shown in the figure below:
■ | Index 0: Adds the suffix ".com" to the host part of the To header. |
■ | Index 1: Changes the user part of the From header to the user part of the P-Asserted-ID. |
■ | Index 2: Changes the user part of the SIP From header to "200". |
■ | Index 3: If the user part of the From header equals "unknown", then it is changed according to the srcIPGroup call’s parameter. |
■ | Index 4: Removes the Priority header from an incoming INVITE message. |
Message Manipulations Parameter Descriptions
Parameter |
Description |
||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
General | |||||||||||||||||||||||||
'Index' [Index] |
Defines an index number for the new table row. Note: Each row must be configured with a unique index. |
||||||||||||||||||||||||
'Name' manipulation-name [ManipulationName] |
Defines a descriptive name, which is used when associating the row in other tables. The valid value is a string of up to 40 characters. |
||||||||||||||||||||||||
'Manipulation Set ID' manipulation-set-id [ManSetID] |
Defines a Manipulation Set ID for the rule. You can define the same Manipulation Set ID for multiple rules to create a group of rules. The Manipulation Set ID is used to assign the manipulation rules to an IP Group (in the IP Groups table) for inbound and/or outbound messages. The valid value is 0 to Note: You can configure up to |
||||||||||||||||||||||||
'Row Role' row-role [RowRole] |
Determines which message manipulation condition (configured by the 'Condition' parameter) to use for the rule.
Note:
|
||||||||||||||||||||||||
Match |
|||||||||||||||||||||||||
'Message Type' message-type [MessageType] |
Defines the SIP message type that you want to manipulate. The valid value is a string (case-insensitive) denoting the SIP message. You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions. For example:
Note: Currently, SIP 100 Trying messages cannot be manipulated. |
||||||||||||||||||||||||
'Condition' condition [Condition] |
Defines the condition that must exist for the rule to be applied. The valid value is a string of up to 200 characters (case-insensitive). You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions. For example:
|
||||||||||||||||||||||||
Action |
|
||||||||||||||||||||||||
'Action Subject' action-subject [ActionSubject] |
Defines the SIP header upon which the manipulation is performed. The valid value is a string (case-insensitive). You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions. |
||||||||||||||||||||||||
'Action Type' action-type [ActionType] |
Defines the type of manipulation.
|
||||||||||||||||||||||||
'Action Value' action-value [ActionValue] |
Defines a value that you want to use in the manipulation. The default value is a string (case-insensitive) in the following syntax:
For example:
You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions. Note: Only single quotation marks must be used. |